Closemul v0.3 
by Denis Trebbi - lustar[at]free[dot]fr
---------------------------------------------------


This is a multi purpose emulator frontend helper:

- Single/multiple hotkey to exit games.
- User defined keyboard automation, for emulators without full command line support.
- Support for third party launchers.
- Unzip / Unrar using 7za and unrar.
- Can run a .bat file found in the archive.
- Can run a .reg file before starting an emulator, for emulators without .ini support.
- Mount/Unmount disc images using Daemon Tools.
- Rename and Move Screenshots when the emulator is closed.
- Create game compilations from Mamewah Lists (GUI only).



To launch zsnes, and close it when a key or key combination is pressed:

ESC:
closemul.exe zsnesw.exe "super mario world.zip"

2+4 for QWERTY keyboards:
closemul.exe 50 52 zsnesw.exe "super mario world.zip"

2+4 for AZERTY keyboards:
closemul.exe 233 39 zsnesw.exe "super mario world.zip"





------------------------------------------------------------------------------------------------------------------
HISTORY
------------------------------------------------------------------------------------------------------------------


v0.3 - First release.
       Before using this program you may want to try "cmd" by Joe Blade, I have been using it with very good results.
       http://www.users.bigpond.net.au/joe_blade/cmd/
       In fact, Closemul was modelled after this program because I liked the way it worked.
       Since "cmd" was inspired by Howard Casto's wrapper, i think credit and thanks must go to both :)
       2006-03-27

v0.2 - The thing has now grown into a multi purpose emulator frontend helper, that replaces all the .bat files i had to use.
       2006-03-05

v0.1 - While setting up emulators in Mamewah I thought I should try getting Caprice32 to automatically run games from
       the frontend (cat, run"game). It couldn't be done with the batch files I used and no "wrapper" seemed to exist
       for this emulator, so I put this together and it turned into an utility to exit emulators with a combination of keys.
       ...Which finally solved something that had been bugging me since I bought an X-Arcade a couple years ago,
       brought it home, and realized that there was no dedicated "exit game" key anywhere.
       2006-02-17





------------------------------------------------------------------------------------------------------------------
FEATURES
------------------------------------------------------------------------------------------------------------------


- Close emulators by a user defined hotkey or by a key combination (defaults to the ESC key).
  This is useful for X-Arcade sticks if you don't want to sacrifice a button to this task, or for emulators that,
  unlike MAME, don't support key combinations settings or don't support setting an exit key at all.

  You can set a single Exit Key, a combination of two Exit Keys, a combination of one or two Exit Keys + ESC (quit=2),
  or map a combination of two Exit Keys to "be ESC" in case the emulator has a setting to exit with ESC but doesn't
  have a setting to exit with a combination of keys (quit=3).
  You can set Closemul to "close only", if you only need to add the key combination feature without launching the program.
  "closemul.exe quit=4 (program.exe)".

  If a particular emulator doesn't seem to respond to your quit hotkey, you can try an alternative method with "quit=5".
  Emulators known to require the alternative method: Nestopia 1.27, Caprice32 3.6.1.
  At last, if you want to use the alternative method + your combination of keys + "ESC", use "quit=6", and "quit=7" for
  the alternative method + your combination of keys = "ESC".

  Usually, you will probably want to use quit=3 as default and quit=2 for emulators that don't offer to set an exit key.

  User defined keys are set by the corresponding decimal ASCII code.
  You can find codes by pressing buttons on your keyboard or control panel from the User Interface part of Closemul. 
  A table of ASCII codes can also be found at the bottom of this file.

  Note that the following keys cannot be used as hotkeys, because they are modifier keys, or reserved by windows:
  Ctrl, Alt, Shift, Win, Delete, F12

  MAME default for X-Arcade/HotRod is 2+4.
  I use 1+3 to close emulators myself, as I find it more intuitive to have the coin1 act as a "shift" key that
  inverts the start1 button's function. There are more chances that you hit the key combination by mistake when
  playing alone, but when you have guests it's easier to close the game yourself than asking your guest to do it.  

  When the Exit key/combination is pressed, Closemul will try to gently close the program first, but will terminate it
  after a short while if it didn't close fast enough. You can increase the TimeOut period using quittimeout=(milliseconds),
  or force the Program to always terminate forcefully without delay using quittimeout="0" (not recommended).



- Support of emulator launchers.
  In case you want to add the features of Closemul (quit + unrar + mount) to another launcher (automated game loading),
  run the other launcher with Closemul (prog=launcher.exe), and set the emulator to be run by the other launcher as
  Program2 (prog2=emulator.exe). Program2 won't be launched, but it will replace the Program to be closed.
  without external launcher:	closemul.exe unrar cue daemon emulator.exe file.ext
  with external launcher:	closemul.exe unrar cue daemon prog2=launcher.exe prog=emulator.exe file.ext



- Keyboard Automation (Automatically load games for emulators that don't support command line)

  For the automation to be active you must use the auto= parameter to set the "Window Title" of your Program.

  You can define a list of keyboard commands to be executed right after the Program is launched, in the .ini or by using
  autosteps="command1,command2" (autosteps="ALT+F, O, FILE, ENTER, F2")

  You can optionally set a time to wait between commands with autodelay= (defaults to 50 milliseconds).

  The list must be comma separated, with or without spaces.
  You can use Special Commands, Prefixes+Keywords, Keywords, or plain text.

  Prefixes: SHIFT+ CTRL+ ALT+ WIN+ (e.g. ALT+F, ALT+TAB, SHIFT+TAB... WIN+ usually requires a lower case letter: WIN+e)

  Keywords:
  F1-F12, ENTER, NUMPADENTER, SPACE, LEFT, UP, DOWN, RIGHT, ESCAPE/ESC, DELETE/DEL, SLEEP, HOME, END, INSERT/INS,
  PGUP, PGDOWN, TAB, PRINTSCREEN, LSHIFT, RSHIFT, LCTRL, RCTRL, LALT, RALT, LWIN, RWIN.

  Special Commands:
  WAIT xx (in milliseconds, wait 1000 will pause for 1 second),
  FILE (will be replaced by the File you specify using the file= parameter),
  FILE2 (will be replaced by the second file found in the archive if you use the unzip/unrar option),
  AFTERFILE (will be replaced by the Param After File parameter),
  ASCII xxxx (you can also use unicode),


  You can also use pre defined automation for some emulators, using keywords in place of the Window Title.

  Project Tempest v0.95: Add "tempest" to your command line.
  (instead of: auto="Project Tempest" autosteps="ALT+F, O, FILE, ENTER, F2")
  
  Caprice32 v3.6.1: Add "caprice" to your command line.
  (instead of: auto=Caprice32 autosteps=", F6, FILE, ENTER, F2, AFTERFILE, ENTER")
  If you want to start with a joystick menu instead of having to type cat, run" on the keyboard, get utility.dsk from
  http://cpc.trak.dk/troels.htm#discexec, load it into Caprice in drive B (F7), type "|b", "run"disc", then press Enter.
  Take a .sna memory snapshot (F4) right after pressing left on the joystick and save it in your Caprice directory.
  Put the name of this .sna file at the end of your command line.
  You will then boot into a joystick controlled menu on the CPC every time you load a game from your frontend.
  
  WinUAE  v1.2.0: Add "winuae" and "config=(yourconfig.uae)" at the end of your command line.
  (auto="WinUAE Properties" autosteps="SHIFT+TAB, SHIFT+TAB, SHIFT+TAB, SHIFT+TAB, F, SPACE, FILE, TAB, ENTER"

  Set all your options, check "Show GUI on Startup" and save your config in the WinUAE "configurations" folder.
  If you use the unzip option and the "winuae" keyword, Closemul will load in drive DF1 any second file present in the archive.



- Automatically extract and run games for emulators that don't support compressed games using 7zip or unrar.

  http://www.7-zip.org/download.html get the "7-Zip Command Line Version".
  "free software distributed under the GNU LGPL."

  http://www.rarlab.com/rar/unrarw32.exe
  The windows command line version of unrar is freeware.
  
  The extracted files are stored in a temporary folder named "closemul-tmp" in the Closemul directory.
  The File that will be loaded with the Program is the first file to be found in the temporary folder.
  You can set the extension of the extracted file if you know the archive contains several files.
  This is Useful if you load disc images ".cue + .bin". You can also set a second extension, in case you know the
  archive could contain two different kinds of file formats for the same system. This is useful if you have some
  disc images stored on the computer as ".iso + .mp3" and some others as ".cue + .bin".
  The temporary folder "closemul-tmp" is deleted when the emulator is closed.



- Run a Program after extraction and before mounting. Usually a path\filename.
  If this option is set to "prebat" (or "preexe"), Closemul will try to find a .bat (or .exe) file in the
  temporary folder and execute it. This is useful if you need to run a file included within your archive before
  you can use the game with an emulator. (for example, PC Engine CD games stored as .iso+.mpc/ogg/mp3).



- Mount disc image using Daemon Tools before launching an emulator. (Unmount when the emulator is closed).
  Tested with Daemon Tools v4.03.
  For this option, you need to install Daemon Tools, configure its drive letter and note the device number.
  You also need to configure your program to use Daemon Tools' virtual drive by default.
  http://www.daemon-tools.cc
  You will also probably need to use an emulator parameter to tell the emulator you want to load a disc.
  When using the keyword "daemon", this setting will use "c:\program files\daemon tools\daemon.exe".
  Extra parameters can be set using mountparam="param1 param2". I never had to use more than "daemon" myself.
  


- Enforce settings from .reg files before launching a game for emulators that don't support saving settings to a file.
  You must create the .reg file manually before you can use this option.
  Here's how: open the start menu, click run, type regedit, enter, in the regedit menu "edit" find "(name of your program".
  when you have found the good entry, export (file, export) the main registry entry (looks like a windows folder)
  to "(name of your executable.reg: pt.reg for pt.exe)" in your program's folder.
  This file contains the program's settings and will be written to the windows registry each time you launch a game
  if you use the registry option.



- Rename and Move Screenshots when the emulator is closed.
  When set, you should see your latest screenshots displayed in the frontend right after you exit the game.

  When those parameters are set, Closemul will try to find in the folder (snapsrc=) a file whose extension is (snapext=) 
  that partially matches the string (snap=). It will then rename it to match the game File and move it to (snapdest=).
  If snap2= and snapdest2= are set, it will try to find a file that matches the string (snap2=) and move it to (snapdest2=).
  
  snapsrc= defaults to the Program directory.
  snapext= defaults to "png".

  The latest screenshots will always overwrite the screenshots in the destination folders.

  The following command will launch ZSnes, then if you have taken two screenshots, it will rename them to match the game File
  that was loaded into ZSnes, copy the first one to "d:\titles" and the second to "d:\screens" when ZSnes is closed.

  closemul.exe snap=0000 snap2=0001 snapext=png snapsrc=snaps snapdest="d:\titles" snapdest2="d:\screens" zsnesw.exe "smw.zip"

  (You will probably want to set up the screenshots related parameters in Closemul.ini)

  You can use the post= setting to convert or resize the screenshots with an external progam before they get renamed/moved.
  (post="bmp2png.exe -q -e snap\*.bmp")
  If bmp2png.exe is placed in the Closemul directory, the keyword "bmp2png" will convert your screenshots from bmp to png. 



- When run, a .log file of the last parameters is created.



- Parameters are set from command line or setting file (.ini).
  Command line always overrides .ini settings.
  Usually, you can fill some basic settings in the .ini file (exit keys, quit behaviour) to be your own default settings,
  and use the command line to complete the default settings with each emulator's particular requirements.

  You can use Command Line prefixes, or omit the prefix if a keyword if available.

  Usually you don't need to use prefixes in the command line for most settings, but in case you need to bypass
  auto detection for a certain Closemul parameter without using its prefix, you can put quotes around some or all of
  the parameters required by the emulator.

  Here are the settings you can use:

---------------------------------------------------------------------------------------------------------
 .ini		|	Prefix		|	Command Line 	|	Parameter
		|			|	Keyword		|
---------------------------------------------------------------------------------------------------------
 Exit Key 1		k=			ASCII key code		ASCII key code
 Exit Key 2		k2=			ASCII key code		ASCII key code
 Extract		extract=		unzip / unrar		unzip / unrar
 Extracted Ext 1	ext=			(ext)			a file extension, without the dot (as in "cue")
 Extracted Ext 2	ext2=			(ext)			a file extension, without the dot (as in "cue")
 Pre  Command		pre=			bat / exe		"(fullpath)\(file.ext)"
 Post Command		post=			bmp2png			"(fullpath)\(file.ext)"
 Mount Program		mount=			daemon  		"(fullpath\daemonexecutable)"
 Mount Device		mountdev=		(single digit)		defaults to 0
 Mount Parameters	mountparam=					put quotes around the whole line: "param1 param2"
 Registry File		reg=			(name).reg		"(name).reg"
 Automation		auto=			tempest 		(Window Title, or keyword)
 Automation Steps	autosteps=					"command1, command2, command3"
 Automation Delay	autodelay=					(milliseconds)
 Program		prog=			(name.exe)		"(name.exe)"
 Program 2		prog2=						"(name.exe)"
 Param Before File				(anything before File)	as required by the Program
 Param After File				(anything after File)	as required by the Program
 File			file=			(name.ext)		"(name.ext)"
 Snap 1 Search		snap=						"(search string)"
 Snap 2 Search		snap2=						"(search string)"
 Snap Extension		snapext=					a file extension, without the dot (as in "png")
 Snap Source Folder	snapsrc=					"(drive\path)" or "(folder)"
 Snap 1 Dest Folder	snapdest=					"(drive\path)"
 Snap 2 Dest Folder	snapdest2=					"(drive\path)"
 Quit Management	quit=						(0: Off / 1: On (Default) / 2: or ESC / 3: = ESC /
									4: Close Only /
									5: MethodB  / 6: MethodB or ESC / 7: MethodB = ESC)
 Quit TimeOut		quittimeout=					(milliseconds)
 Disable Quotes		* noquotes=		noquotes		1 Disable quotes



 Here is the order in which the various options take place:

 extract to a temp folder,
 run a command,
 mount a disc image,
 write a .reg file in registry,
 run your program,
 automation steps,
 close your program,
 run a command,
 rename/move screenshots,
 delete the temporary folder.



- (GUI only) Create game compilations from Mamewah Lists (Tested with Mamewah 1.62)
  You can copy the games you have selected in your Mamewah Games Lists to a new folder, provided that your Source rom path
  contains subfolders matching Mamewah's configuration files.
  (MamewahFiles)\mame-1.lst must match (SourceRoms)\mame\
  (MamewahFiles)\snes-1.lst must match (SourceRoms)\snes\
  This should work for other frontends as well as long as the list contains some lines that only consist of valid filenames.

  Don't worry if you use Split Sets for MAME, Mamewah includes the parents and bios in its lists so they won't be left out.

  Run Closemul without any parameter, then in the menu click "Tool>List to Files for Mamewah",
  Input or Browse for your Source and Destination paths (Destination defaults to "(source)-Fav" and is created if needed),
  If files already exist in the Destination folder, they will not be overwritten,
  Input or Browse for your Mamewah Lists folder (Mamewah\Files),
  Set the List Search String and Extension as needed (defaults to -1 and lst), click "Select Lists" to see the matched lists,
  Select the systems you want to create compilations for, or click "Check All" then click "Copy Selection".

  


------------------------------------------------------------------------------------------------------------------
INSTALLATION
------------------------------------------------------------------------------------------------------------------


- Copy the Closemul files in the folders of the emulators you plan on using. (you can use File>Install/Uninstall in the GUI).
  It could probably work placed in its own directory, but then full path information would be needed for every file,

- If you have your emulator already configured in a frontend and just want to exit it with the ESC key,
  simply add closemul.exe before the emulator executable in the emulator command line.

- If you want to use the extract feature for emulators that don't support compressed games,
  For zip files, place the 7zip standalone executable 7za.exe in the emulator directory.
  For rar files, place the unrar.exe executable in the emulator directory.

- If you want to use the mount/unmount feature, install Daemon Tools (tested with v4.03).





------------------------------------------------------------------------------------------------------------------
USAGE
------------------------------------------------------------------------------------------------------------------


closemul.exe (exitkey1) (exitkey2) (unzip/unrar) prog.exe (file.ext)


To load a compressed disc image stored as .cue+.iso+.bat(audio extractor) and compressed using .rar into Magic Engine:

closemul.exe 50 52 unrar cue bat daemon "path\pce.exe" "path\dracula.rar" "syscard3.pce"
=
closemul.exe k=50 k2=52 extract=unrar ext=cue pre=bat mount="c:\program files\daemon tools\daemon.exe" mountdev=0 prog="path\pce.exe" file="path\dracula.rar" "syscard3.pce"




Examples for the Mamewah frontend:


- To close program.exe when a key combination is pressed
  "2+4" (Coin2+Start2 in MAME): 50 52 (QWERTY) or 233 39 (AZERTY).
  "1+3" (Coin1+Start3 in MAME): 49 51 (QWERTY) or 38 34 (AZERTY).

emulator_commandline    d:\mamewah\emulators\program\closemul.exe program.exe 50 52 "[rompath]\[name].[romext]" {nodosbox}{nosafelaunch}




Examples assuming you set the Exit Keys in the Closemul.ini file as default settings:


Zsnes
emulator_commandline    d:\mamewah\emulators\Zsnes\closemul.exe zsnesw.exe "[rompath]\[name].[romext]" {dosbox}{safelaunch}

Nestopia (requires quit method B)
emulator_commandline    d:\mamewah\emulators\Nestopia\closemul.exe quit=7 nestopia.exe "[rompath]\[name].[romext]" {nodosbox}{safelaunch}

Project Tempest v0.95 (unzip + use a .reg file to enforce settings + automation)
emulator_commandline    d:\mamewah\emulators\Project_Tempest\closemul.exe unzip "pt-settings.reg" tempest "pt.exe" "[rompath]\[name].[romext]" {nodosbox}{safelaunch}

Caprice32 v3.6.1 (unzip + automation)
emulator_commandline    d:\mamewah\emulators\Caprice\closemul.exe unzip quit=6 caprice caprice32.exe "[rompath]\[name].[romext]" "utility.sna" {nodosbox}{safelaunch}

WinUAE  v1.2.0 (unzip + automation)
emulator_commandline    d:\mamewah\emulators\WinUAE\closemul.exe unzip quit=7 winuae winuae.exe "[rompath]\[name].[romext]" -config="config.uae" {nodosbox}{safelaunch}

Chankast v0.25 + Chankast Launch v1.3 (unrar + mount + load using Chankast Launch)
emulator_commandline    d:\mamewah\emulators\Chankast\closemul.exe unrar cdi daemon file="[rompath]\[name].[romext]" prog2="chankast.exe" prog="chankast_launch.exe" "-chankast chankast.exe -fullscreen -exit -showstats" {nodosbox}{safelaunch}

Kega Fusion for MegaCD (unrar expecting to find a cue or iso file in the archive)
emulator_commandline    d:\mamewah\emulators\Kega_Fusion\closemul.exe unrar iso cue fusion.exe "[rompath]\[name].[romext]" -fullscreen {nodosbox}{nosafelaunch}

Magic Engine (unrar expecting to find a cue file in the archive + extract using a .bat file if found + mount)
emulator_commandline    d:\mamewah\emulators\Magic_Engine\closemul.exe unrar cue bat daemon pce.exe "[rompath]\[name].[romext]" syscard3.pce {nodosbox}{safelaunch}

Project64 (no quotes + use a .reg file to enforce settings)
emulator_commandline    d:\mamewah\emulators\Project64\closemul.exe noquotes "project64.reg" project64.exe [rompath]\{8.3[name]}.[romext] {nodosbox}{safelaunch}

HandyHack (Handy 0.90 modified) (use a .reg file to enforce settings)
emulator_commandline    d:\mamewah\emulators\Handy-h\closemul.exe handy-h.reg handy-h.exe -d=2 -z=1 -g="[rompath]\[name].[romext]" {nodosbox}{safelaunch}

PSX (unrar expecting to find a cue file in the archive + mount)
emulator_commandline    d:\mamewah\emulators\PSX\closemul.exe unrar cue psxfin.exe -f "[rompath]\[name].rar" {dosbox}{safelaunch}





------------------------------------------------------------------------------------------------------------------
QWERTY and AZERTY ASCII codes
------------------------------------------------------------------------------------------------------------------


azerty	ASCII	QWERTY	|	AZERTY	ASCII	qwerty
lower		UPPER	|	UPPER		lower
------------------------|------------------------------
a 	97 	Q 	|	A 	65 	q
b 	98 	B 	|	B 	66 	b
c 	99 	C 	|	C 	67 	c
d 	100 	D 	|	D 	68 	d
e 	101 	E 	|	E 	69 	e
f 	102 	F 	|	F 	70 	f
g 	103 	G 	|	G 	71 	g
h 	104 	H 	|	H 	72 	h
i 	105 	I 	|	I 	73 	i
j 	106 	J 	|	J 	74 	j
k 	107 	K 	|	K 	75 	k
l 	108 	L 	|	L 	76 	l
m 	109 	, 	|	M 	77 	:
n 	110 	N 	|	N 	78 	n
o 	111 	O 	|	O 	79 	o
p 	112 	P 	|	P 	80 	p
q 	113 	A 	|	Q 	81 	a
r 	114 	R 	|	R 	82 	r
s 	115 	S 	|	S 	83 	s
t 	116 	T 	|	T 	84 	t
u 	117 	U 	|	U 	85 	u
v 	118 	V 	|	V 	86 	v
w 	119 	Z 	|	W 	87 	z
x 	120 	X 	|	X 	88 	x
y 	121 	Y 	|	Y 	89 	y
z 	122 	W 	|	Z 	90 	w
$ 	36 	] 	|	 	163(156)]
 	249(235)' 	|	% 	37 	'
* 	42 	\ 	|	 	130 	\
< 	60 	\ 	|	> 	62 	\
, 	44 	m 	|	? 	63 	M
 	231(59)	, 	|	. 	46 	,
: 	58 	. 	|	/ 	47 	.
! 	33 	/ 	|	 	245 	/
& 	38 	1 	|	1 	49 	1
 	233(130)2 	|	2 	50 	2
" 	34 	3 	|	3 	51 	3
' 	39 	4 	|	4 	52 	4
( 	40 	5 	|	5 	53 	5
-	45		|	6	54	6
 	232(138)7 	|	7 	55 	7
_	95 	8 	|	8 	56 	8
; 	59(135)	9 	|	9 	57 	9
 	224(133)0 	|	0 	48 	0
) 	41 	- 	|	 	248 	-
= 	61 	= 	|	+ 	43 	=
~ 	152(126)2	|	 	  	 
# 	35 	3 	| 	  	 
{ 	123 	4  	|	  	 
[ 	91 	5	|	  	  	 
|	124 	6	|	  	  	 
` 	96 	7	|	  	  	 
\ 	92 	8	|	  	  	 
^ 	94 	9	|  	 
@ 	64 	-	|	  	  	 
] 	93 	-	|	  	  	 
} 	125 	=	|
 	178		|
TAB	09 		|
BACKSPC 08		|
SPACE	32  		|
ESC	27	ESC	|	ESC	27	ESC		  	  	 

